Mappings Applications to CMDB

Introduction

note

Creating custom application mappings is only supported with Cherwell. With ServiceNow, you can use only the built-in mappings.

The Application Mapping tab allows you to specify the CMDB table to write application information to as well as the Resolve Insights application fields that you want to synchronize. You can also enable or disable mappings after you create them.

Default Mappings

The Application Mappings table includes mapping suggestions to help you more easily configure the mappings that you want. You can edit a mapping to customize it for your needs, you can delete it, or you can disable it.

If you can't find the mapping you want, you can create new mappings.

Creating an Application Mapping

Creating allows you to configure a mapping for a new combination of the Insights table and CMDB system fields.

You can create duplicating mappings as long as only one of them is enabled. Insights determines duplicates by the CMDB System field - you can only have one active mapping for a given CMDB system.

Take these steps to create an application mapping:

1. Go to Settings > CMDB Mappings > Application Mappings.
2. Click Add New.
3. On the Application Field Mapping page, fill in the following fields:
   • Table Name - The name of the CMDB table to which you want to push data from Insights. Example: ConfigSystem
   • CMDB System - Select the CMDB system to push to.
   • Mandatory Fields - Optional. Used only with the Use Script field mapping option. Enter the list of Elasticsearch fields that must be included in the initial table query. To require a field, enter its name as it appears in Elasticsearch and then click the plus sign. Non-existing fields will have null as a value in the request response.
   • Restricted Fields - Optional. Enter a list of application fields that you don't want pushed to the CMDB even if they are mapped. To restrict a field, enter its name as it appears in Elasticsearch and then click the plus sign.
   • Enable Mapping - Switch the toggle if you want to enable the mapping as soon as you create it.
4. Click Continue.
5. (Optional) On the Field Mapping page, map application fields to target CMDB fields.
   Repeat to add as many fields as you need.
6. Click Save & Complete.
7. (Optional) Back at the Application Mapping table, test your mapping.

Testing an Application Mapping

You can test-run a mapping after you create one or edit an existing mapping. The test run ensures that you have set the mappings properly on the Insights side but does not test your connection with the CMDB or if the CMDB table and field names that you provided are correct.

Take these steps to test a mapping:

1. Go to Settings > CMDB Mappings > Application Mappings.
2. In the mapping's Actions column, click the Test Mapping icon.
   The Test Mapping dialog box appears.
3. In the Application Id field, select the application to test and then click Test Mapping.
4. Check the returned record.
   You should see the filtered Insight record the way it will be pushed to the CMDB, with all mapping options applied.
   note

   To let you more easily read the data when testing Cherwell mappings, the screen shows the Cherwell column names instead of the Cherwell column IDs. In the actual push request sent to Cherwell, however, column names are replaced with the corresponding column IDs.

Editing an Application Mapping

You can edit all details of a mapping, including the table mapping and the field mapping.

Take these steps to edit an application mapping:

1. Go to Settings > CMDB Mappings > Application Mappings.
2. In the mapping's Actions column, click the Edit (pencil) icon.
3. Edit the fields as necessary:
   • For editing the settings on the Application Field Mapping tab, refer to Creating an Application Mapping.
   • For editing the settings on the Field Mapping tab, refer to Mapping Application Fields.
4. Click Save & Close.
5. (Optional) Back at the Application Mapping table, test your mapping.

Mapping Application Fields

Field mapping allows you to more granularly match the Insights data to the CMDB table structure. You can specify which target table field will store each Insights table field.

You can map application fields during the initial application mapping creation or later when editing a mapping.

On the Field Mapping page, use the controls described below to create an application field mapping.

Starting and Saving a Field Mapping

Click the Add New Field button to open a new device field mapping form. You can add as many field mappings as you like.

Click the Save Field button on the form to save the mapping.

Specifying the CMDB Field Name

In the CMDB Field Name text field, enter the exact name of the target table field as it appears in your CMDB.

Specifying the Insights Field Name

You have two alternative options to specify the Insights field name that you want to map to CMDB Field Name. Use the radio buttons to select one of the following options:

• Insights Field - Choose this option to manually specify the details of the Elasticsearch field that you want to map to the CMDB field. The following fields appear:
  • Insights Field - Enter the name of the Elasticsearch field that you are mapping.
  • Fallback Field - Enter the name of an Elasticsearch field to read the value from if the Insights Field is null.
  • Default Value - Enter a value to be used in case neither Insights Field nor Fallback Field contains a value.
  • Overridding Value - Enter a value to be used regardless of what value is found in Insights Field.
• Use Script - Choose this option to provide a Painless script to extract field data from the Elasticsearch database to map to the CMDB field. The following field appears:
  • Painless Script - Enter the Painless script code that returns an Elasticsearch field value. Using a script is useful when you want to create a JSON object that closely matches the data structure expected by your CMDB.

Painless script example:

if (doc.containsKey('hostName') && doc['hostName'].value != null) {
    def hostName = doc['hostName'].value;
    def match = hostName + '.';
    def resultMatch = hostName;
    def found = false;
    if (doc.containsKey(params.meridianFieldName) && doc[params.meridianFieldName].value != null) {
        if (doc[params.meridianFieldName].length == 1) {
            resultMatch = doc[params.meridianFieldName][0]
        } else {
            for (s in doc[params.meridianFieldName]) {
                if (s.startsWith(match)) {
                    if (!found) {
                        resultMatch = s;
                        found = true;
                    } else {
                        resultMatch = hostName;
                        break;
                    }
                }
            }
        }
    }
    return resultMatch;
}
if (params.fallBackFieldName != null && doc.containsKey(params.fallBackFieldName)) {
    return doc[params.fallBackFieldName].value;
}

Modifying the Insights Field

After specifying the Elasticsearch field using the Insights Field or Use Script options, you can optionally use various operators to modify the value of the field before pushing it to the CMDB.

Check Use Operator to enable value modification.

Conditional Operator

Use this operator to modify the pushed value if it is found or not found in the Elasticsearch field.

Fill in the form as follows:

• If the value of the "Mapping" is equal to - Enter the value that you expect to appear in the Elasticsearch field. Only single values are supported.
• Use value - Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is found.
• Else, use value - Optional. Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is not found.

Example: If the value of devSubType is equal to Bare Metal, push Physical Appliance, else push Virtual Appliance.

Split Operator

Use this operator when you want to push only a part of the value found in Elasticsearch.

• Use as separator - Enter a character or a string at which to split the Elasticsearch value into several parts.
• Limit the maximum parts to split to - Specify how many parts you want to end up with starting on the left. For example, if you specify 4, Insights will do three splits at the first three separators it finds. All further instances of the separator will remain integrated within the fourth part.
• Return Part - Enter the number of the part that you want to return. Parts are numbered from left to right starting at 1.

Example: To extract the subnet and machine part of a 172.16.x.x IPv4 address, enter . as a separator, 3 as a limit and then return part number 3, which should yield you the x.x part.

Deleting Application Mappings

You can delete one or more device mappings simultaneously.

To delete mappings, check their boxes in the first table column and then click Delete.

Enabling and Disabling Application Mappings

You can disable mappings one at a time. Insights ignores disabled mappings when pushing service data to the CMDB but you can still test disabled mappings.

To disable a mapping, switch the toggle in the Enable column.